Skip to content

Docs: Add weight parameter documentation for Weighted RRF retriever #136698

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Docs: Add weight parameter documentation for Weighted RRF retriever #136698

wants to merge 13 commits into from
+125 −19

Conversation

mridula-s109
Copy link
Contributor

@mridula-s109 mridula-s109 commented Oct 16, 2025 •
edited
Loading

Summary

Adds missing documentation for the weight parameter introduced with the Weighted RRF retriever (GA'd in #130658).

Closes #136477

Changes

rrf-retriever.md (REST API Reference):

  • Added sub-parameters section documenting retriever and weight fields
  • Added weighted hybrid search example showing weight usage
  • Follows linear-retriever.md documentation patterns

retrievers-examples.md (Examples Guide):

  • Updated main RRF example to demonstrate weighted retrievers
  • Shows semantic search (weight 2.0) and lexical search (weight 1.0)

Testing

  • ./gradlew :docs:check passed (917 tasks completed)
  • Documentation-only changes

Checklist

Related

@mridula-s109 mridula-s109 requested review from a team, Copilot, leemthompo and pmpailis October 16, 2025 13:50
@mridula-s109 mridula-s109 self-assigned this Oct 16, 2025
@mridula-s109 mridula-s109 added >docs General docs changes Team:Docs Meta label for docs team :SearchOrg/Relevance Label for the Search (solution/org) Relevance team Team:Search Relevance Meta label for the Search Relevance team in Elasticsearch labels Oct 16, 2025
@mridula-s109 mridula-s109 marked this pull request as ready for review October 16, 2025 13:50
@mridula-s109 mridula-s109 mentioned this pull request Oct 16, 2025
Open
4 tasks
Copilot
Copilot AI reviewed Oct 16, 2025
View reviewed changes
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds documentation for the weight parameter in the Weighted RRF retriever, which was previously introduced but lacked proper documentation. The changes provide comprehensive examples and parameter descriptions to help users understand how to adjust retriever influence in RRF ranking.

  • Added detailed documentation for retriever and weight sub-parameters in the RRF retriever
  • Added weighted hybrid search example showing different weight configurations
  • Updated the main RRF example to demonstrate weighted retrievers with semantic vs lexical search weighting

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
docs/reference/elasticsearch/rest-apis/retrievers/rrf-retriever.md Added weight parameter documentation, sub-parameters section, and weighted hybrid search example
docs/reference/elasticsearch/rest-apis/retrievers/retrievers-examples.md Updated main RRF example to use weighted format with semantic search having higher influence

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@elasticsearchmachine elasticsearchmachine added v9.3.0 Team:Search - Relevance The Search organization Search Relevance team and removed Team:Search Relevance Meta label for the Search Relevance team in Elasticsearch labels Oct 16, 2025
@elasticsearchmachine
Copy link
Collaborator

Pinging @elastic/search-relevance (Team:Search - Relevance)

@elasticsearchmachine
Copy link
Collaborator

Pinging @elastic/core-docs (Team:Docs)

@github-actions
Copy link
Contributor

github-actions bot commented Oct 16, 2025 •
edited
Loading

🔍 Preview links for changed docs

@github-actions
Copy link
Contributor

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

@leemthompo
Copy link
Contributor

Hey @mridula-s109 remember per the comment, that we can't just overwrite info from a previous version, we need to use applies_to tags to make it clear what changed in 9.2 without deleting any information that's relevant to 9.0 + 9.1 :)

@mridula-s109
Copy link
Contributor Author

Hey @mridula-s109 remember per the comment, that we can't just overwrite info from a previous version, we need to use applies_to tags to make it clear what changed in 9.2 without deleting any information that's relevant to 9.0 + 9.1 :)

Ah yes, it slipped my mind. i will update the changes accordingly.

kderusso
kderusso reviewed Oct 20, 2025
View reviewed changes
Copy link
Member

@kderusso kderusso left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good overall, some comments on vocabulary

@mridula-s109 mridula-s109 requested a review from Copilot October 22, 2025 12:25
Copilot
Copilot AI reviewed Oct 22, 2025
View reviewed changes
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@mridula-s109 mridula-s109 requested a review from kderusso October 22, 2025 12:32
kderusso
kderusso reviewed Oct 22, 2025
View reviewed changes
Copy link
Member

@kderusso kderusso left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work, I think we're almost there!

docs/reference/elasticsearch/rest-apis/retrievers/retrievers-examples.md
"query_string": {
"query": "(information retrieval) OR (artificial intelligence)",
"default_field": "text"
"retriever": {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The old syntax still works when not specifying weights, correct? Should we keep both examples in the docs?

docs/reference/elasticsearch/rest-apis/retrievers/rrf-retriever.md

Applies the specified [boolean query filter](/reference/query-languages/query-dsl/query-dsl-bool-query.md) to all of the specified sub-retrievers, according to each retriever’s specifications.

Each entry in the `retrievers` array can be specified in two ways:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This still seems confusing. I would replace this paragraph with bringing back the earlier example, and have two complete examples, one specifying weights and one not.

docs/reference/elasticsearch/rest-apis/retrievers/rrf-retriever.md
4. This retriever has a weight of 1.0 (default weight).

::::{note}
You can mix weighted and non-weighted formats in the same query.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is OK, provided you link to the more explicit examples in the retriever docs that I suggested above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kderusso kderusso kderusso left review comments

Copilot code review Copilot Copilot left review comments

@pmpailis pmpailis Awaiting requested review from pmpailis

@leemthompo leemthompo Awaiting requested review from leemthompo

At least 1 approving review is required to merge this pull request.

Assignees

@mridula-s109 mridula-s109

Labels

>docs General docs changes :SearchOrg/Relevance Label for the Search (solution/org) Relevance team Team:Docs Meta label for docs team Team:Search - Relevance The Search organization Search Relevance team v9.3.0

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add missing weight parameter documentation for Weighted RRF retriever and update elasticsearch-specification

4 participants

@mridula-s109 @elasticsearchmachine @leemthompo @kderusso